
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>

<HEAD>
   <TITLE>diags2_c</TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<A name="TOP"></A>

<table style="text-align: left; margin-left: auto; margin-right: auto; width: 800px;"
 border="0" cellpadding="5" cellspacing="2">
  <tbody>
    <tr>
      <td style="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
      <div align="right"> 
      <small><small><a href="index.html">Index Page</a></small></small>
      </div>
      <b>diags2_c</b> </td>
    </tr>

    <tr>
      <td style="vertical-align: top;">

<small><div align="center">
<A HREF="index.html#A">A</A>&nbsp;
<A HREF="index.html#B">B</A>&nbsp;
<A HREF="index.html#C">C</A>&nbsp;
<A HREF="index.html#D">D</A>&nbsp;
<A HREF="index.html#E">E</A>&nbsp;
<A HREF="index.html#F">F</A>&nbsp;
<A HREF="index.html#G">G</A>&nbsp;
<A HREF="index.html#H">H</A>&nbsp;
<A HREF="index.html#I">I</A>&nbsp;
<A HREF="index.html#J">J</A>&nbsp;
<A HREF="index.html#K">K</A>&nbsp;
<A HREF="index.html#L">L</A>&nbsp;
<A HREF="index.html#M">M</A>&nbsp;
<A HREF="index.html#N">N</A>&nbsp;
<A HREF="index.html#O">O</A>&nbsp;
<A HREF="index.html#P">P</A>&nbsp;
<A HREF="index.html#Q">Q</A>&nbsp;
<A HREF="index.html#R">R</A>&nbsp;
<A HREF="index.html#S">S</A>&nbsp;
<A HREF="index.html#T">T</A>&nbsp;
<A HREF="index.html#U">U</A>&nbsp;
<A HREF="index.html#V">V</A>&nbsp;
<A HREF="index.html#W">W</A>&nbsp;
<A HREF="index.html#X">X</A>&nbsp;
</div></small>
       <br>
       <table style="text-align: left; width: 60%; margin-left: auto; margin-right: auto;"
       border="0" cellspacing="2" cellpadding="2">
        <tbody>
          <tr>
            <td style="width: 50%; text-align: center;">
            <small>
              <a href="#Procedure">Procedure<br></a>
              <a href="#Abstract">Abstract<br></a>
              <a href="#Required_Reading">Required_Reading<br></a>
              <a href="#Keywords">Keywords<br></a>
              <a href="#Brief_I/O">Brief_I/O<br></a>
              <a href="#Detailed_Input">Detailed_Input<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Detailed_Output">Detailed_Output<br></a>
              <a href="#Parameters">Parameters<br></a>
              <a href="#Exceptions">Exceptions<br></a>
              <a href="#Files">Files<br></a>
              <a href="#Particulars">Particulars<br></a>
              <a href="#Examples">Examples<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Restrictions">Restrictions<br></a>
              <a href="#Literature_References">Literature_References<br></a>
              <a href="#Author_and_Institution">Author_and_Institution<br></a>
              <a href="#Version">Version<br></a>
              <a href="#Index_Entries">Index_Entries<br></a>
             </small>
            </td>
          </tr>
        </tbody>
</table>

<h4><a name="Procedure">Procedure</a></h4>
<PRE>
   void diags2_c ( ConstSpiceDouble    symmat [2][2],
                   SpiceDouble         diag   [2][2],
                   SpiceDouble         rotate [2][2]  ) 

</PRE>
<h4><a name="Abstract">Abstract</a></h4>
<PRE>
 
   Diagonalize a symmetric 2x2 matrix. 
 </PRE>
<h4><a name="Required_Reading">Required_Reading</a></h4>
<PRE>
 
   <a href="../req/rotation.html">ROTATION</a>
 </PRE>
<h4><a name="Keywords">Keywords</a></h4>
<PRE>
 
   ELLIPSE 
   MATRIX 
   ROTATION 
   TRANSFORMATION 
 

</PRE>
<h4><a name="Brief_I/O">Brief_I/O</a></h4>
<PRE>
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
 
   symmat     I   A symmetric 2x2 matrix. 
   diag       O   A diagonal matrix similar to symmat. 
   rotate     O   A rotation used as the similarity transformation. 
 </PRE>
<h4><a name="Detailed_Input">Detailed_Input</a></h4>
<PRE>
 
   symmat         A symmetric 2x2 matrix.  That is, symmat has the 
                  form 
 
                     +-        -+ 
                     |  A    B  | 
                     |          |. 
                     |  B    C  | 
                     +-        -+ 
 
                  This routine uses only the upper-triangular 
                  elements of symmat, that is, the elements 
 
                     symmat[0][0] 
                     symmat[0][1] 
                     symmat[1][1] 
 
                  to determine the outputs diag and rotate. 
 </PRE>
<h4><a name="Detailed_Output">Detailed_Output</a></h4>
<PRE>
 
   diag, 
   rotate         are, respectively, a diagonal matrix and a 2x2 
                  rotation matrix that satisfy the equation 
 
                                      T 
                     diag   =   rotate    *  symmat  *  rotate. 
 
                  In other words, diag is similar to symmat, and 
                  rotate is a change-of-basis matrix that 
                  diagonalizes symmat.  <b>diags2_c</b> chooses rotate so 
                  that its angle of rotation has the smallest 
                  possible magnitude.  If there are two rotations 
                  that meet these criteria (they will be inverses of 
                  one another), either rotation may be chosen. 
 </PRE>
<h4><a name="Parameters">Parameters</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Exceptions">Exceptions</a></h4>
<PRE>
 
   Error free.
   
   
   1)  The matrix element symmat[1][0] is not used in this routine's 
       computations, so the condition 
 
          symmat[0][1]  !=  symmat[1][0] 
 
       has no effect on this routine's outputs. 
 </PRE>
<h4><a name="Files">Files</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Particulars">Particulars</a></h4>
<PRE>
 
   The capability of diagonalizing a 2x2 symmetric matrix is 
   especially useful in a number of geometric applications 
   involving quadratic curves such as ellipses.  Such curves are 
   described by expressions of the form 
 
         2                    2 
      A x   +   B xy   +   C y   +   D x    +    E y   +   F   =   0. 
 
   Diagonalization of the matrix 
 
      +-         -+ 
      | A     B/2 | 
      |           | 
      | B/2     C | 
      +-         -+ 
 
   allows us to perform a coordinate transformation (a rotation, 
   specifically) such that the equation of the curve becomes 
 
         2         2 
      P u   +   Q v   +   R u    +    S v   +   T   =   0 
 
   in the transformed coordinates.  This form is much easier to 
   handle.  If the quadratic curve in question is an ellipse, 
   we can easily find its center, semi-major axis, and semi-minor 
   axis from the second equation. 
 
   Ellipses turn up frequently in navigation geometry problems; 
   for example, the limb and terminator (if we treat the Sun as a 
   point source) of a body modelled as a tri-axial ellipsoid are 
   ellipses. 
 
   A mathematical note:  because symmat is symmetric, we can ALWAYS 
   find an orthogonal similarity transformation that diagonalizes 
   symmat, and we can choose the similarity transformation to be a 
   rotation matrix.  By `orthogonal' we mean that if the rotate is 
   the matrix in question, then 
 
            T                         T 
      rotate  rotate  =  rotate rotate  =  I. 
 
   The reasons this routine handles only the 2x2 case are:  first, 
   the 2x2 case is much simpler than the general case, in which 
   iterative diagonalization methods must be used, and second, the 
   2x2 case is adequate for solving problems involving ellipses in 
   3 dimensional space.  Finally, this routine can be used to 
   support a routine that solves the general-dimension diagonalization 
   problem for symmetric matrices. 
 
   Another feature of the routine that might provoke curiosity is 
   its insistence on choosing the diagonalization matrix that 
   rotates the original basis vectors by the smallest amount.  The 
   rotation angle of rotate is of no concern for most applications, 
   but can be important if this routine is used as part of an 
   iterative diagonalization method for higher-dimensional matrices. 
   In that case, it is most undesirable to interchange diagonal 
   matrix elements willy-nilly; the matrix to be diagonalized could 
   get ever closer to being diagonal without converging.  Choosing 
   the smallest rotation angle precludes this possibility. 
 </PRE>
<h4><a name="Examples">Examples</a></h4>
<PRE>
 
   1)  A case that can be verified by hand computation: 
       Suppose symmat is 
 
          +-            -+ 
          |  1.0    4.0  | 
          |              | 
          |  4.0   -5.0  | 
          +-            -+ 
 
       Then symmat is similar to the diagonal matrix 
 
          +-            -+ 
          |  3.0    0.0  | 
          |              | 
          |  0.0   -7.0  |
          +-            -+ 
 
       so 
 
          diag[0][0] =  3. 
          diag[1][0] =  0. 
          diag[0][1] =  0. 
          diag[1][1] = -7. 
 
       and rotate is 
 
          +-                                             -+ 
          |  0.89442719099991588    -0.44721359549995794  | 
          |                                               | 
          |  0.44721359549995794     0.89442719099991588  | 
          +-                                             -+ 
 
      which is an approximation to 
 
          +-                                   -+ 
          |  .4 * 5**(1/2)     -.2 * 5**(1/2)   | 
          |                                     | 
          |  .2 * 5**(1/2)      .4 * 5**(1/2)   | 
          +-                                   -+ 
 
 
   2)  Suppose we want to find the semi-axes of the ellipse defined 
       by 
              2                 2 
          27 x  +  10 xy  +  3 y   =  1
 
       We can write the above equation as the matrix equation 
 
          +-     -+  +-         -+  +- -+ 
          | x   y |  | 27     5  |  | x |    =   1
          +-     -+  |           |  |   | 
                     |  5     3  |  | y | 
                     +-         -+  +- -+ 
 
       Let symmat be the symmetric matrix on the left.  The code 
       fragment 
 
          symmat[0][0]  =  27.0;
          symmat[1][0]  =   5.0; 
          symmat[0][1]  =   5.0; 
          symmat[1][1]  =   3.0; 
 
          <b>diags2_c</b> ( symmat, diag, rotate ); 
 
       will return diag, an array containing the eigenvalues of 
       symmat, and rotate, the coordinate transformation required 
       to diagonalize symmat.  In this case, 
 
          diag[0][0]   =  28. 
          diag[1][0]   =   0. 
          diag[0][1]   =   0. 
          diag[1][1]   =   2. 
 
        and 
 
          rotate[0][0] =   0.980580675690920 
          rotate[1][0] =   0.196116135138184 
          rotate[0][1] =  -0.196116135138184 
          rotate[1][1] =   0.980580675690920 
 
       The columns of rotate give the ellipse's axes, after scaling 
       them by 
 
                 1                            1 
          ----------------     and     --------------- 
            ____________                 ____________ 
          \/  diag[0][0]               \/  diag[1][1] 
 
       respectively. 
 
       If smajor and sminor are semi-major and semi-minor axes, 
       we can find them as shown below.  For brevity, we omit the 
       check for zero or negative eigenvalues.  
 
          for ( i = 0;  i &lt; 2;  i++ )
          {
             smajor[i] = rotate[i][0]  /  sqrt( diag[0][0] ); 
             sminor[i] = rotate[i][1]  /  sqrt( diag[1][1] ); 
          }
 </PRE>
<h4><a name="Restrictions">Restrictions</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Literature_References">Literature_References</a></h4>
<PRE>
 
   [1]  Calculus, Vol. II.  Tom Apostol.  John Wiley &amp; Sons, 1969. 
        See Chapter 5, `Eigenvalues of Operators Acting on Euclidean 
        Spaces'. 
 </PRE>
<h4><a name="Author_and_Institution">Author_and_Institution</a></h4>
<PRE>
 
   N.J. Bachman   (JPL) 
 </PRE>
<h4><a name="Version">Version</a></h4>
<PRE>
 
   -CSPICE Version 1.0.0, 13-JUL-1999 (NJB)
</PRE>
<h4><a name="Index_Entries">Index_Entries</a></h4>
<PRE>
 
   diagonalize symmetric 2x2_matrix 
 </PRE>
<h4>Link to routine diags2_c source file <a href='../../../src/cspice/diags2_c.c'>diags2_c.c</a> </h4>

      </td>
    </tr>
  </tbody>
</table>

   <pre>Wed Jun  9 13:05:21 2010</pre>

</body>
</html>

